﻿ #region Disclaimer/Info
 
 /////////////////////////////////////////////////////////////////////////////////////////////////
 //
 //   File:		IPageService.cs
 //   Website:		http://dexterblogengine.com/
 //   Authors:		http://dexterblogengine.com/About.ashx
 //   Rev:		1
 //   Created:		19/01/2011
 //   Last edit:		19/01/2011
 //   License:		GNU Library General Public License (LGPL)
 //   File:            IPageService.cs
 //   For updated news and information please visit http://dexterblogengine.com/
 //   Dexter is hosted to Codeplex at http://dexterblogengine.codeplex.com
 //   For any question contact info@dexterblogengine.com
 //
 ///////////////////////////////////////////////////////////////////////////////////////////////////
 
 #endregion
 

using System;
using System.Collections.Generic;
using System.ComponentModel;
using Dexter.Core.EventArgs;
using Dexter.DataTransferObject;
using Dexter.Domain.Model;
using Dexter.Domain.Results;

namespace Dexter.Services {
	/// <summary>
	/// 	Rapresents the gateway for all service to save, retrieve and manipulate data for <see cref = "Page" />.
	/// </summary>
	public interface IPageService : IDomainService {

		///<summary>
		///	Retrieve the list of all pages slugs
		///</summary>
		///<returns>
		///	Return a list of <c>string</c> base on <see cref="Item.Slug"/> property.
		///	It could be null if there aren't items into the repository.
		///</returns>
		IList <string> GetAllSlugs ( );

		///<summary>
		///	Retrieve the list of <see cref="PageStructure"/>
		///</summary>
		///<returns>
		///	It could be null if there aren't items into the repository.
		///</returns>
		IEnumerable <PageStructure> GetPagesStructure ( );

		///<summary>
		///	Retrieve the list of <see cref="PageStructureDto"/>
		///</summary>
		///<returns>
		///	It could be null if there aren't items into the repository.
		///</returns>
		IEnumerable<PageStructureDto> GetPagesStructureDto ( );

		///<summary>
		///	Retrieve the root list of <see cref="PageStructure"/>
		/// This can be used to generate a pages' menu
		///</summary>
		///<returns>
		///	It could be null if there aren't items into the repository.
		///</returns>
		IEnumerable<PageStructure> GetPagesStructureRoot();

		///<summary>
		///	Retrieve the root list of <see cref="PageStructureDto"/>
		/// This can be used to generate a pages' menu
		///</summary>
		///<returns>
		///	It could be null if there aren't items into the repository.
		///</returns>
		IEnumerable<PageStructureDto> GetPagesStructureDtoRoot ( );

		///<summary>
		///	Retireve a paged list of all <see cref="Page"/>.
		///</summary>
		/// <remarks>
		///		The result will include only published pages and past pages, unpublished and future will be excluded.
		///		Moreover the result hasn't the tracking system enabled
		/// </remarks>
		///<param name = "pageIndex">Index of the page (0 based).</param>
		///<param name = "pageSize">The number of items to retrieve.</param>
		///<returns>An concrete implementation of <see cref="IPagedResult{T}"/>. The result will never be null.</returns>
		IPagedResult <Page> GetPages ( int pageIndex , int pageSize );

		///<summary>
		///	Retrieve a <see cref="Page"/> for a specified slug.
		///</summary>
		///<param name = "slug">The slug.</param>
		///<returns>
		///	An instance of <see cref="Page"/>.
		///	It could be null if there isn't an item with the specified slug into the repository.
		///</returns>
		Page GetBySlug ( string slug );

		///<summary>
		///	Retrieve a <see cref="Page"/> for a specified slug.
		///</summary>
		///<param name = "slug">The slug.</param>
		///<param name = "enableTracking">if set to <c>true</c> the tracking system of the return object will be enable.</param>
		///<returns>
		///	An instance of <see cref="Page"/>.
		///	It could be null if there isn't an item with the specified slug into the repository.
		///</returns>
		Page GetBySlug ( string slug, bool enableTracking );

		/// <summary>
		/// Gets the by key.
		/// </summary>
		/// <param name="key">The key.</param>
		/// <returns>
		/// An instance of <see cref="Page"/>.
		///	It could be null if there isn't an item with the specified key into the repository.
		/// </returns>
		Page GetByKeyWithParent(int key);

		/// <summary>
		/// Gets the by key.
		/// </summary>
		/// <param name="key">The key.</param>
		///<param name = "enableTracking">if set to <c>true</c> the tracking system of the return object will be enable.</param>
		/// <returns>
		/// An instance of <see cref="Page"/>.
		///	It could be null if there isn't an item with the specified key into the repository.
		/// </returns>
		Page GetByKeyWithParent(int key, bool enableTracking);

		/// <summary>
		/// 	Deletes the page with the specified key, from the repository.
		/// </summary>
		/// <param name = "key">The key.</param>
		///<exception cref="ArgumentOutOfRangeException"> If <paramref name="key"/> is lesser than 1.</exception>
		void Delete(int key);

		/// <summary>
		/// 	Saves the specified page into the repository.
		/// </summary>
		/// <param name = "item">The item.</param>
		void Save(Page item);

		/// <summary>
		/// 	Updates the specified page into the repository.
		/// </summary>
		/// <param name = "item">The item.</param>
		void Update(Page item);

		/// <summary>
		/// This event will raise before <see cref="Page"/> will be retrieved by the implementation of <see cref="GetBySlug(string)"/>.
		/// </summary>
		event EventHandler<CancelEventArgsWithOneParameterWithReturnItem<string, Page>> PageRetrieving;

		/// <summary>
		/// This event will raise before <see cref="Page"/> will be retrieved by the implementation of <see cref="GetByKeyWithParent(int)"/>.
		/// </summary>
		event EventHandler<CancelEventArgsWithOneParameterWithReturnItem<int, Page>> PageRetrievingByKey;

		/// <summary>
		/// This event will raise after <see cref="Page"/> will be retrieved by the implementation of <see cref="GetBySlug(string)"/>.
		/// </summary>
		event EventHandler<GenericEventArgs<Page>> PageRetrieved;

		/// <summary>
		/// This event will raise before <see cref="Page"/> will be retrieved by the implementation of <see cref="GetPages(int,int)"/>.
		/// </summary>
		event EventHandler<CancelEventArgsWithOneParameterWithReturnItem<Tuple<int, int>, IPagedResult<Page>>> PagesRetrieving;

		/// <summary>
		/// This event will raise after <see cref="Page"/> will be retrieved by the implementation of <see cref="GetPages(int,int)"/>.
		/// </summary>
		event EventHandler<GenericEventArgs<IPagedResult<Page>>> PagesRetrieved;

		/// <summary>
		/// This event will raise before <see cref="Page"/> will be retrieved by the implementation of <see cref="GetPagesStructure()"/>.
		/// </summary>
		event EventHandler<CancelEventArgsWithReturnItem<IEnumerable<PageStructure>>> PagesStructureRetrieving;

		/// <summary>
		/// This event will raise after <see cref="Page"/> will be retrieved by the implementation of <see cref="GetPagesStructure()"/>.
		/// </summary>
		event EventHandler<GenericEventArgs<IEnumerable<PageStructure>>> PagesStructureRetrieved;

		/// <summary>
		/// This event will raise before slugs will be retrieved by the implementation of <see cref="GetAllSlugs()"/>.
		/// </summary>
		event EventHandler<CancelEventArgsWithReturnItem<IList<string>>> SlugRetrieving;

		/// <summary>
		/// This event will raise after a slugs will be retrieved by the implementation of <see cref="GetAllSlugs()"/>.
		/// </summary>
		event EventHandler<GenericEventArgs<IList<string>>> SlugRetrieved;

		/// <summary>
		/// This event will raise before a <see cref="Page"/> will be deleted by the implementation of <see cref="Delete(int)"/>.
		/// </summary>
		event EventHandler<CancelEventArgsWithOneParameter<int>> PageDeleting;

		/// <summary>
		/// This event will raise after a <see cref="Page"/> will be deleted by the implementation of <see cref="Delete(int)"/>.
		/// </summary>
		event EventHandler<GenericEventArgs<Page>> PageDeleted;

		/// <summary>
		/// This event will raise before a <see cref="Page"/> will be saved by the implementation of <see cref="Save(Page)"/>.
		/// </summary>
		event EventHandler<CancelEventArgsWithOneParameter<Page>> PageSaving;

		/// <summary>
		/// This event will raise after a <see cref="Page"/> will be saved by the implementation of <see cref="Save(Page)"/>.
		/// </summary>
		event EventHandler<GenericEventArgs<Page>> PageSaved;

		/// <summary>
		/// This event will raise before a <see cref="Page"/> will be saved by the implementation of <see cref="Update(Page)"/>.
		/// </summary>
		event EventHandler<CancelEventArgsWithOneParameter<Page>> PageUpdating;

		/// <summary>
		/// This event will raise after a <see cref="Page"/> will be saved by the implementation of <see cref="Update(Page)"/>.
		/// </summary>
		event EventHandler<GenericEventArgs<Page>> PageUpdated;
	}
}
